home *** CD-ROM | disk | FTP | other *** search
/ User's Choice Windows CD / User's Choice Windows CD (CMS Software)(1993).iso / win_a_d / aspdll.zip / PDLLSPEC.TXT < prev    next >
Text File  |  1992-07-08  |  5KB  |  157 lines
  1. Writing Dynamic Link Libraries
  2. for
  3. The Windows ASPECT Script Language
  4.  
  5. Pascal Language Interface Specification
  6.  
  7. Introduction
  8.  
  9.     PROCOMM PLUS for Windows implements a powerful scripting language called the 
  10. Windows ASPECT Script Language (ASPECT).  One of ASPECT's great strengths is the ability 
  11. to call functions embedded in Dynamic Link Libraries (or DLLs) written and compiled outside of 
  12. ASPECT.  This paper focuses on the writing of DLLs for ASPECT using Turbo Pascal*  for 
  13. Windows* (TPW) from Borland International, Inc.
  14.  
  15. ASPECT to DLL Parameter Sequence
  16.  
  17.     ASPECT generates a standard parameter block for every DLL call that it makes.  This 
  18. standard parameter block has five parameters, listed in order below.  When writing a DLL to be 
  19. called from ASPECT, every exported function that is to be accessible from within ASPECT 
  20. should declare exactly these number and types of parameters:
  21.  
  22.     1.    [HWnd] - a handle to the PROCOMM PLUS for Windows main window.
  23.     2.    [THandle] - a handle to the instance of PROCOMM PLUS for Windows that made 
  24. the DLL call.
  25.     3.    [pointer to array[0..9] of pointer] - a pointer to an array of pointers to the data 
  26. elements listed as parameters on the ASPECT script line that called the DLL 
  27. function.
  28.     4.    [pointer to array[0..9] of byte] - a pointer to an array of bytes.  Byte N of this 
  29. array describes the type of element N stored in the array of data elements (i.e. 
  30. parameter 3).  The range of values in this array follows:
  31.  
  32.             Byte
  33.             Value    Meaning                         
  34.               0    nth element is an ASPECT string
  35.               1    nth element is an ASPECT integer
  36.               2    nth element is an ASPECT long
  37.               3    nth element is an ASPECT float
  38.  
  39.     5.    [int] - an integer containing the count of parameters provided on the ASPECT 
  40. script line calling the DLL function.
  41.  
  42. An Example
  43.  
  44.     Below is the code for a DLL with a function that generates a random number.  Under a 
  45. PASCAL style, stack-based parameter passing scheme, a variable number of parameters is not 
  46. normally possible; however, ASPECT provides an array-based parameter passing scheme as 
  47. described by the parameter block above.  To demonstrate the ability to pass a variable number of 
  48. parameters, the DLL function listed below makes certain assumptions about the provided 
  49. parameters based on the number of parameters that are available:
  50.  
  51.     1.    If two parameters are passed to the DLL function:
  52.         a.    the first parameter holds a long integer for seeding the random-number 
  53. generator.
  54.         b.    the second parameter will hold the return value (i.e. the random number).
  55.  
  56.     2.    If one parameter is passed to the DLL function:
  57.         a.    the DLL function should seed the random number generator using 
  58. Randomize function (from the TPW System Unit).
  59.         b.    the single parameter will hold the return value (i.e. the random number).
  60.  
  61. Here is the code for the DLL.  This is RANDINT.PAS:
  62.  
  63. library RandInt;
  64. uses WinTypes;
  65.  
  66. const
  67.   IntegerType = 1;
  68.   LongType = 2;
  69.   MaxWord: Word = 65535;
  70.  
  71. type
  72.   pdatptrary = ^tdatptrary;
  73.   tdatptrary = array[0..9] of pointer;
  74.   ptypptrary = ^ttypptrary;
  75.   ttypptrary = array[0..9] of byte;
  76.  
  77. function RandomInt(PWWnd: HWnd; PWInst: THandle; PData: pdatptrary;
  78.   PType: ptypptrary; argcnt: integer): BOOL; export;
  79. begin
  80.   if (argcnt < 1) then
  81.     begin                        {at least one arg?}
  82.       RandomInt := FALSE;        {if not, return failure to Aspect}
  83.       exit;
  84.     end;
  85.   if (argcnt > 1) then
  86.     begin
  87.       if ((PType^[0] <> LongType) or (PType^[1] <> IntegerType)) then
  88.         begin
  89.           RandomInt := FALSE;    {for two args, 1=long, 2=int}
  90.           exit;                  {if not, return failure to Aspect}
  91.         end;
  92.       RandSeed := PLongint(PData^[0])^;       {seed generator}
  93.       PWord(PData^[1])^ := Random(MaxWord);   {get the random number}
  94.     end
  95.   else
  96.     begin
  97.       if (PType^[0] <> IntegerType) then
  98.         begin
  99.           RandomInt := False;    {for one arg, 1=int}
  100.           exit;                  {if not, return failure to Aspect}
  101.         end;
  102.       Randomize;                              {seed generator with time}
  103.       PWord(PData^[0])^ := Random(MaxWord);   {get the random number}
  104.     end;
  105.   RandomInt := True;             {return success to aspect}
  106. end;
  107.  
  108. exports
  109.   RandomInt index 1;
  110.  
  111. begin
  112. end.
  113.  
  114.  
  115. Here is an ASPECT script using the DLL.  This is RANDINT.WAS:
  116.  
  117. ;ASPECT script demonstrating RANDINT.DLL
  118. integer hdll, rnum
  119. long seed = 1060665
  120.  
  121. proc cleanup
  122.   dllfree hdll
  123.   exit
  124. endproc
  125.  
  126. proc main
  127. string DLLPATH = "C:\PROWIN\ASPECT\RANDINT.DLL" ;path to the DLL
  128.  
  129.   when userexit call cleanup              ;point to cleanup routine
  130.   dllload DLLPATH hdll                    ;load the DLL
  131.   if (failure)
  132.     usermsg "dllload failed"
  133.     exit
  134.   endif
  135.  
  136.   ;generate a random number letting the DLL use system time as seed
  137.   dllcall hdll "RandomInt" rNum
  138.   if (failure)
  139.     usermsg "RandomInt call with system time seed failed"
  140.     cleanup()
  141.   else
  142.     usermsg "RandomInt with system time seed returned %u" rNum
  143.   endif
  144.  
  145.   ;generate a random number with the our seed
  146.   dllcall hdll "RandomInt" seed rNum
  147.   if (failure)
  148.     usermsg "RandomInt call with our seed failed"
  149.     cleanup()
  150.   else
  151.     usermsg "RandomInt with our seed returned %u" rNum
  152.   endif
  153.  
  154.   cleanup()
  155. endproc
  156.  
  157.